home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / nihcl-30.lha / nihcl-3.0 / README < prev   
INI File  |  1993-01-01  |  55KB  |  1,447 lines
  1. [Note: This file has been modified by the Free Software Foundation]
  2.  
  3.  
  4.  
  5.  
  6.  
  7.        Release Notes  NIH Class Library Revision 3.0  Release Notes
  8.  
  9.  
  10.  
  11.  
  12.             INTRODUCTION
  13.  
  14.             These are the release notes for Revision 3.0 of the NIH Class
  15.             Library.  This release contains the following classes:
  16.  
  17.             NIHCL---Library Static Member Variables and Functions
  18.                 Object---Root of the NIH Class Library Inheritance Tree
  19.                     Bitset---Set of Small  Integers  (like  Pascal's  type
  20.             SET)
  21.                     Class---Class Descriptor
  22.                     Collection---Abstract Class for Collections
  23.                         Arraychar---Byte Array
  24.                         ArrayOb---Array of Object Pointers
  25.                         Bag---Unordered Collection of Objects
  26.                         SeqCltn---Abstract  Class  for  Ordered,   Indexed
  27.             Collections
  28.                             Heap---Min-Max Heap of Object Pointers
  29.                             LinkedList---Singly-Linked List
  30.                             OrderedCltn---Ordered  Collection  of   Object
  31.             Pointers
  32.                                 SortedCltn---Sorted Collection
  33.                                     KeySortCltn---Keyed Sorted Collection
  34.                             Stack---Stack of Object Pointers
  35.                         Set---Unordered   Collection   of    Non-Duplicate
  36.             Objects
  37.                             Dictionary---Set of Associations
  38.                                 IdentDict---Dictionary  Keyed  by   Object
  39.             Address
  40.                             IdentSet---Set Keyed by Object Address
  41.                     Date---Gregorian Calendar Date
  42.                     FDSet---Set of File Descriptors for Use with select(2)
  43.             System Call
  44.                     Float---Floating Point Number
  45.                     Fraction---Rational Arithmetic
  46.                     Integer---Integer Number Object
  47.                     Iterator---Collection Iterator
  48.                     Link---Abstract Class for LinkedList Links
  49.                         LinkOb---Link Containing Object Pointer
  50.                         Process---Co-routine Process Object
  51.                             HeapProc---Process with Stack in Free Store
  52.                             StackProc---Process with Stack on main() Stack
  53.                     LookupKey---Abstract Class for Dictionary Associations
  54.                         Assoc---Association of Object Pointers
  55.  
  56.  
  57.  
  58.             May 25, 1990                                          Page 1
  59.  
  60.  
  61.  
  62.  
  63.  
  64.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  65.  
  66.  
  67.                         AssocInt---Association  of  Object  Pointer   with
  68.             Integer
  69.                     Nil---The Nil Object
  70.                     Point---X-Y Coordinate Pair
  71.                     Random---Random Number Generator
  72.                     Range---Range of Integers
  73.                     Rectangle---Rectangle Object
  74.                     Scheduler---Co-routine Process Scheduler
  75.                     Semaphore---Process Synchronization
  76.                     SharedQueue---Shared Queue of Objects
  77.                     String---Character String
  78.                         Regex---Regular Expression
  79.                     Time---Time of Day
  80.                     Vector---Abstract Class for Vectors
  81.                         BitVec---Bit Vector
  82.                         ByteVec---Byte Vector
  83.                         ShortVec---Short Integer Vector
  84.                         IntVec---Integer Vector
  85.                         LongVec---Long Integer Vector
  86.                         FloatVec---Floating Point Vector
  87.                         DoubleVec---Double-Precision Floating Point Vector
  88.                 OIOifd---File Descriptor Object I/O readFrom() Formatting
  89.                 OIOin---Abstract   Class   for   Object   I/O   readFrom()
  90.             Formatting
  91.                     OIOistream---Abstract  Class  for  Stream  Object  I/O
  92.             readFrom() Formatting
  93.                         OIOnihin---Stream Object I/O readFrom() Formatting
  94.                 OIOofd---File Descriptor Object I/O storeOn() Formatting
  95.                 OIOout---Abstract   Class   for   Object   I/O   storeOn()
  96.             Formatting
  97.                     OIOostream---Abstract  Class  for  Stream  Object  I/O
  98.             storeOn() Formatting
  99.                         OIOnihout---Stream Object I/O storeOn() Formatting
  100.                 ReadFromTbl---Tables used by Object I/O readFrom()
  101.                 StoreOnTbl---Tables used by Object I/O storeOn()
  102.  
  103.  
  104.  
  105.             CHANGES BETWEEN OOPS V2R2 AND NIHCL R3.0
  106.  
  107.             This section highlights the most significant changes that have
  108.             been  made since the previous release.  It is by no stretch of
  109.             the imagination complete.
  110.  
  111.             Library name changed from "OOPS" to "NIH Class Library"
  112.             (NIHCL)
  113.  
  114.             Since there's too many things called "OOPS" these days,  we've
  115.             changed  the  name  of our library to the "NIH Class Library".
  116.             All file and C++ names containing "OOPS"  have  been  changed,
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.             Page 2                                          May 25, 1990
  125.  
  126.  
  127.  
  128.  
  129.  
  130.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  131.  
  132.  
  133.             often just by substituting "NIHCL" for "OOPS".
  134.  
  135.             Class NIHCL
  136.  
  137.             With the introduction of static member functions and  (useful)
  138.             static  member  variables  in  R2.0,  it  is  now  possible to
  139.             eliminate most global names.  In  R3.0,  we've  gathered  many
  140.             previously global functions and variables and made them static
  141.             members of a new class, NIHCL, which  is  the  base  class  of
  142.             Object.  Here's a list of the public functions:
  143.  
  144.                  static class NIHCL {
  145.                  // ...
  146.                  public:             // static member functions
  147.                      static unsigned char charBitMask(int i);
  148.                      static unsigned short shortBitMask(int i);
  149.                      static unsigned int intBitMask(int i);
  150.                      static unsigned char bitCount(int i);
  151.                      static unsigned char bitReverse(int i);
  152.                      static void initialize();           // library
  153.                  initialization
  154.                      static bool initialized();          // library
  155.                  initialized?
  156.                      static void setError(int error, int sev ...);
  157.                  } NIHCL_init;
  158.  
  159.             Since all NIH Library classes  inherit  these  members,  their
  160.             member  functions  can  use  these  names  without  needing to
  161.             specify a scope  qualifier,  except  to  resolve  ambiguities.
  162.             However,  non-member functions and member functions of classes
  163.             not derived from NIHCL can access them with  the  NIHCL  scope
  164.             qualifier; for example:
  165.  
  166.                  NIHCL::setError(ERROR_CODE, DEFAULT);
  167.  
  168.             Optional support for multiple inheritance
  169.  
  170.             The NIH Class Library can  be  compiled  to  support  Multiple
  171.             Inheritance  (MI) by defining the preprocessor symbol MI.  All
  172.             classes linked together  in  a  program  must  all  have  been
  173.             compiled with the same MI option setting.  The major effect of
  174.             this switch is that all classes derived from Object specify it
  175.             as  a virtual base class.  Since C++ does not permit a pointer
  176.             to a virtual base class to be cast down  to  a  pointer  to  a
  177.             derived  class,  the  new  DECLARE_MEMBERS  macro  defines  an
  178.             overloaded family of static member functions named  castDown()
  179.             that  can  perform  this  conversion.  (If  MI is not enabled,
  180.             castDown() becomes an ordinary pointer cast.)
  181.  
  182.             The castDown() functions all call the function _castDown()  to
  183.             perform  the pointer conversion.  If a class has only a single
  184.             base class, it uses the DEFINE_CLASS and DEFINE_ABSTRACT_CLASS
  185.             preprocessor   macros   as   before,  and  these  generate  an
  186.             implementation  of  _castDown()  suitable   for   the   single
  187.  
  188.  
  189.  
  190.             May 25, 1990                                          Page 3
  191.  
  192.  
  193.  
  194.  
  195.  
  196.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  197.  
  198.  
  199.             inheritance  case.   If  a class has multiple base classes, it
  200.             uses  the  new  DEFINE_CLASS_MI  and  DEFINE_ABSTRACT_CLASS_MI
  201.             macros, which do not generate _castDown()---the class provider
  202.             must supply a definition as described in Template_c.
  203.  
  204.             All  readFrom()  constructors  must  specify  the   readFrom()
  205.             constructor  for  the  virtual  base  class  Object  in  their
  206.             initialization lists when MI is enabled.  See  Template_h  for
  207.             details.
  208.  
  209.             If you use virtual base classes in conjunction  with  the  NIH
  210.             Class  Library,  you  must  take  care  when  implementing the
  211.             deepCopy()  and  storeOn()  operations  that  a  virtual  base
  212.             class's  member  variables  are  only deepened or stored once.
  213.             The  library  provides   the   functions   deepenVBase()   and
  214.             storeVBaseOn()  to help with this.  Call deepenVBase() instead
  215.             of deepenShallowCopy() to deepen the  member  variables  of  a
  216.             virtual   base  class,  and  call  storeVBaseOn()  instead  of
  217.             storer() to store the  member  variables  of  a  virtual  base
  218.             class.
  219.  
  220.             DECLARE_MEMBERS  macro
  221.  
  222.             The  new  DECLARE_MEMBERS  preprocessor  macro  generates  the
  223.             declarations  for  the class descriptor and most of the member
  224.             functions  that  all  NIH  Library   classes   must   provide,
  225.             including:
  226.  
  227.                  private:
  228.                          static Class classDesc;         // class
  229.                  descriptor
  230.                  public:
  231.                          classname* castDown(Object*);
  232.                          const classname* castDown(const Object*);
  233.                          classname& castDown(Object&);
  234.                          const classname& castDown(const Object&);
  235.                          static const Class* desc();             // return
  236.                  class descriptor
  237.                          static classname* readFrom(OIOin&);
  238.                          static classname* readFrom(OIOifd&);
  239.                          classname(OIOin&);                      //
  240.                  readFrom() constructors
  241.                          classname(OIOout&);
  242.                          virtual const Class* isA() const;
  243.                          virtual Object* shallowCopy() const;
  244.                          virtual void* _castdown(const Class&) const;
  245.                  protected:
  246.                     void deepenVBase();
  247.                          void storeVBaseOn(OIOofd&) const;       // store
  248.                  virtual base class
  249.                          void storeVBaseOn(OIOout&) const;
  250.                  private:
  251.                          static Object* reader(OIOin& strm);
  252.                          static Object* reader(OIOifd& fd);
  253.  
  254.  
  255.  
  256.             Page 4                                          May 25, 1990
  257.  
  258.  
  259.  
  260.  
  261.  
  262.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  263.  
  264.  
  265.             The DECLARE_MEMBERS macro takes a single argument, the name of
  266.             the class being declared.
  267.  
  268.             New implementation of Process classes
  269.  
  270.             In R3.0, class Process has two derived classes, StackProc  and
  271.             HeapProc,   which   serve  as  the  base  classes  for  client
  272.             processes.  StackProc and HeapProc differ in where a process's
  273.             stack  is located when the process is running: a StackProc has
  274.             its stack located on the real  stack  in  the  stack  segment,
  275.             while a HeapProc has its stack in the free storage area in the
  276.             data segment.   A  context  switch  of  a  StackProc  involves
  277.             copying  the active part of the current process's stack into a
  278.             save area, then copying the saved stack  of  the  new  process
  279.             onto  the real stack.  A context switch of a HeapProc involves
  280.             simply resetting  the  processor's  stack  pointer  and  frame
  281.             pointer  registers  to  point to the new stack, so a StackProc
  282.             context switch is much slower than a HeapProc context  switch.
  283.             However,  using  HeapProcs  tends  to  break  debuggers, which
  284.             usually  can't  cope  with  the  bizarre  stack  location,  so
  285.             programs  using  them are difficult to debug.  Also, the stack
  286.             area for a HeapProc must be specified when it is  constructed,
  287.             and  must  be  large enough to hold the largest stack that can
  288.             occur anytime during execution.  In contrast, the  stack  save
  289.             area  for a StackProc grows in size if necessary and must only
  290.             be large enough to hold the largest  stack  in  use  when  the
  291.             process is suspended.  Thus, the tradeoff is debuggability and
  292.             reduced memory requirement vs. speed.
  293.  
  294.             Fiddling  with  the  stack  area  and  machine  registers   is
  295.             something  you  can't  do  directly from C++, so processes are
  296.             inherently  non-portable.   The  R3.0  implementation  of  the
  297.             Process  classes  attempts  to  use  the  C  library  routines
  298.             setjmp(), longjmp(), and alloca()  to  do  context  switching.
  299.             While  this works on many machines, you may need to write your
  300.             own versions of  these  routines  for  machines  on  which  it
  301.             doesn't.   See  the section on PORTING THE PROCESS CLASSES for
  302.             instructions.
  303.  
  304.             External class_classname identifiers eliminated
  305.  
  306.             The class descriptor for each class no longer has an  external
  307.             identifier  of  the  form class_classname.  Instead, the class
  308.             descriptor is a static member variable of each class, and  the
  309.             inline static member function desc() returns its address.
  310.  
  311.             Changes to Object I/O
  312.  
  313.             Previous releases of OOPS have a fundamental  problem  in  the
  314.             way  they  handle object I/O for classes with member variables
  315.             that are class instances.  For example, consider an OOPS class
  316.             X  with  a member variable of class M, where M is also an OOPS
  317.             class:
  318.  
  319.  
  320.  
  321.  
  322.             May 25, 1990                                          Page 5
  323.  
  324.  
  325.  
  326.  
  327.  
  328.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  329.  
  330.  
  331.                  class X : public BASE {
  332.                      M m;    // a member class instance
  333.                      M* p;   // a member pointer to a class instance
  334.                      int i;  // a fundamental type
  335.                  // ...
  336.                  };
  337.  
  338.             Previous releases implement X::storer() and  X::X(istream&,X&)
  339.             as follows:
  340.  
  341.                  void X::storer(ostream& strm)
  342.                  {
  343.                      BASE::storer(strm);
  344.                      m.storeOn(strm);
  345.                      p->storeOn(strm);
  346.                      strm << i << " ";
  347.                  }
  348.  
  349.                  void X::X(istream&strm, X& where)
  350.                      : (strm,where)
  351.                  {
  352.                      this = &where;
  353.                      readFrom(strm,"M",m);
  354.                      p = (M*)readFrom(strm,"M");
  355.                      strm >> i;
  356.                  }
  357.  
  358.                  void X::storer(FileDescTy& fd)
  359.                  {
  360.                      BASE::storer(fd);
  361.                      m.storeOn(fd);
  362.                      p->storeOn(fd);
  363.                      storeBin(fd,i);
  364.                  }
  365.  
  366.                  void X::X(FileDescTy& fd, X& where)
  367.                      : (fd,where)
  368.                  {
  369.                      this = &where;
  370.                      readFrom(fd,"M",m);
  371.                      p = (M*)readFrom(fd,"M");
  372.                      readBin(fd,i);
  373.                  }
  374.  
  375.             The problem is that this constructor first initializes m using
  376.             the   M::M()   constructor,   then   calls  readFrom(),  which
  377.             overwrites  this  initialized  instance   with   an   instance
  378.             constructed  by  reading  strm.   We  didn't  notice  this bug
  379.             earlier because, in  practice,  the  problem  occurs  only  in
  380.             classes   Rectangle   and  SharedQueue,  and  has  no  obvious
  381.             consequences. The worst that  is  likely  to  happen  is  that
  382.             M::M() allocates some memory that never gets reclaimed.
  383.  
  384.             Unfortunately, the fix requires some widespread changes.  But,
  385.  
  386.  
  387.  
  388.             Page 6                                          May 25, 1990
  389.  
  390.  
  391.  
  392.  
  393.  
  394.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  395.  
  396.  
  397.             it turns out that numerous other improvements become possible.
  398.             The  new  format  for  storer()   functions   and   readFrom()
  399.             constructors when not using MI is:
  400.  
  401.                  void X::storer(OIOout& strm)
  402.                  {
  403.                      BASE::storer(strm);
  404.                      m.storeMemberOn(strm);
  405.                      p->storeOn(strm);
  406.                      strm << i;
  407.                  }
  408.  
  409.                  void X::X(OIOin& strm)
  410.                      : (strm), m(strm)
  411.                  {
  412.                      p = M::readFrom(strm);
  413.                      strm >> i;
  414.                  }
  415.  
  416.                  void X::storer(OIOofd& fd)
  417.                  {
  418.                      BASE::storer(fd);
  419.                      m.storeMemberOn(fd);
  420.                      p->storeOn(fd);
  421.                      fd << i;
  422.                  }
  423.  
  424.                  void X::X(OIOifd& fd)
  425.                      : (fd), m(fd)
  426.                  {
  427.                      p = M::readFrom(fd);
  428.                      fd >> i;
  429.                  }
  430.  
  431.             The new format is simpler and consistent---storer()  functions
  432.             always   call  BASE::storer()  and  X::X(OIOin&)  constructors
  433.             always call BASE::BASE(OIOin&).
  434.  
  435.             Public readFrom() constructor
  436.  
  437.             Since  other  classes  in  general   must   have   access   to
  438.             X::X(OIOin&),   it   must  be  public  instead  of  protected,
  439.             requiring a change to all header files.
  440.  
  441.             Changes to readFrom()
  442.  
  443.             As explained previously, calls to readFrom() that specify  the
  444.             third  argument  overwrite an initialized instance of a class.
  445.             Since this is generally a bad thing to do, the third  argument
  446.             to  readFrom() has been eliminated; thus, readFrom() will only
  447.             return a pointer to an object. This  form  of  readFrom()  was
  448.             used  to initialize member class instances.  These must now be
  449.             initialized via the readFrom() constructor in the  initializer
  450.             list,  as shown in the example.  When converting old programs,
  451.  
  452.  
  453.  
  454.             May 25, 1990                                          Page 7
  455.  
  456.  
  457.  
  458.  
  459.  
  460.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  461.  
  462.  
  463.             these calls to readFrom() will be flagged  as  errors  because
  464.             the  three  argument  form of readFrom() is no longer defined.
  465.             Note that when you change the readFrom() constructor, you must
  466.             also  change  the corresponding storer() function to store the
  467.             member using storeMemberOn() rather than storeOn().
  468.  
  469.             In previous releases, the second argument to readFrom() was an
  470.             optional  name  of the class of object that was expected to be
  471.             read.  If the object read was of a different class, readFrom()
  472.             raised    an    error.     Beginning    with   this   release,
  473.             readFrom(OIOin&),  and  readFrom(OIOifd&)  are  static  member
  474.             functions of each class which will also accept derived classes
  475.             of the specified class, just as C++  allows  a  pointer  to  a
  476.             derived class to be used instead of a pointer to a base class.
  477.             The global functions readFrom(istream, const char*  classname)
  478.             and   readFrom(int   fd,  const  char*  classname)  have  been
  479.             eliminated.
  480.  
  481.             istream& replaced by OIOin&
  482.  
  483.             The  type  of  the  first  (and  now  only)  argument  to  the
  484.             constructors  called  by  readFrom(istream&)  has been changed
  485.             from an istream& to an OIOin&.  This avoids  naming  conflicts
  486.             with  other  constructors.   Also,  OIOin  is an abstract base
  487.             class, and all input operators are virtual functions,  so  you
  488.             can  customize  the  Object  I/O  format  by defining your own
  489.             derived classes.   OIOistream and OIOnihin implement a  format
  490.             similar to the old OOPS format.
  491.  
  492.             ostream& replaced by OIOout&
  493.  
  494.             The type of the argument to the storer(ostream&) function  has
  495.             been  changed   to  an  OIOout&.   OIOout  is an abstract base
  496.             class, and all output operators are virtual functions, so  you
  497.             can  customize  the  Object  I/O  format  by defining your own
  498.             derived classes. OIOostream and OIOnihout implement  a  format
  499.             similar to the old OOPS format.
  500.  
  501.             Automatic separators output by OIOostream::operator<<()
  502.  
  503.             It is no longer necessary to explicitly output a  space  after
  504.             each  number  written in a storer(OIOnihout&) function.  Class
  505.             OIOostream  reimplements  operator<<()  to  supply  the  space
  506.             automatically.
  507.  
  508.             FileDescTy& replaced by OIOifd&/OIOofd&
  509.  
  510.             The type of the argument to the  storer(FileDescTy&)  function
  511.             has  been  changed   to  an  OIOofd&.  and the argument to the
  512.             readFrom(FileDescTy&) function has been changed to an OIOifd&.
  513.             OIOifd  and  OIOofd  are  not  abstract classes, and their I/O
  514.             operators are not virtual functions as in OIOin and OIOout, so
  515.             using  them  does not incur the overhead of a virtual function
  516.  
  517.  
  518.  
  519.  
  520.             Page 8                                          May 25, 1990
  521.  
  522.  
  523.  
  524.  
  525.  
  526.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  527.  
  528.  
  529.             call for each member variable.
  530.  
  531.             Change to readFrom(OIOin&)
  532.  
  533.             Encountering EOF during  readFrom(OIOin&)  is  now  always  an
  534.             error.  Previous releases returned nil if the input stream was
  535.             initially at  the  EOF.   readFrom(OIOin&)  now  behaves  like
  536.             readFrom(OIOifd&) always has.
  537.  
  538.             storeBin() replaced by OIOofd::operator<<() and OIOofd::put()
  539.  
  540.             The function storeBin(FileDescTy&, type) has been replaced  by
  541.             OIOofd::operator<<(type)        and        the        function
  542.             storeBin(FileDescTy&, type*, unsigned) has  been  replaced  by
  543.             OIOofd::put(type*, unsigned).
  544.  
  545.             readBin() replaced by OIOifd::operator>>() and OIOifd::get()
  546.  
  547.             The function readBin(FileDescTy&, type) has been  replaced  by
  548.             OIOifd::operator>>(type) and the function readBin(FileDescTy&,
  549.             type*,  unsigned)  has  been  replaced  by  OIOifd::get(type*,
  550.             unsigned).
  551.  
  552.             read_Cstring() replaced by OIOin::getCstring()
  553.  
  554.             The   function   read_Cstring()   has   been    replaced    by
  555.             OIOin::getCstring().
  556.  
  557.             store_Cstring() replaced by OIOout::putCstring()
  558.  
  559.             The   function   store_Cstring()   has   been   replaced    by
  560.             OIOout::putCstring().
  561.  
  562.             READ_OBJECT_AS_BINARY eliminated
  563.  
  564.             The READ_OBJECT_AS_BINARY macro has been eliminated.   Replace
  565.             it  with  code  to read member variables individually using >>
  566.             and get().
  567.  
  568.             STORE_OBJECT_AS_BINARY eliminated
  569.  
  570.             The STORE_OBJECT_AS_BINARY macro has been eliminated.  Replace
  571.             it  with  code to store member variables individually using <<
  572.             and put().
  573.  
  574.             Changes to the DEFINE_CLASS macro
  575.  
  576.             The new version  of  the  DEFINE_CLASS  macro  has  hooks  for
  577.             supporting    multiple   inheritance.   Before   calling   the
  578.             DEFINE_CLASS  macro,  you  must  define   three   preprocessor
  579.             symbols:        BASE_CLASSES,        MEMBER_CLASSES,       and
  580.             VIRTUAL_BASE_CLASSES.  As an example, suppose you are  writing
  581.             the implementation of a class with the following declaration:
  582.  
  583.  
  584.  
  585.  
  586.             May 25, 1990                                          Page 9
  587.  
  588.  
  589.  
  590.  
  591.  
  592.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  593.  
  594.  
  595.                  class X: public A, public virtual B {
  596.                      C c;        // C is a class
  597.                      D d;        // D is a class
  598.                  //...
  599.                  };
  600.  
  601.             Set the symbol BASE_CLASSES to a list of the addresses of  the
  602.             class  descriptors  for  the base classes of the class you are
  603.             defining.  These must be in the same order as they  appear  in
  604.             the class declaration:
  605.  
  606.                  #define BASE_CLASSES A::desc(), B::desc()
  607.  
  608.             Set the symbol MEMBER_CLASSES to a list of  the  addresses  of
  609.             the  class  descriptors  for any member variables of the class
  610.             that are NIH Library classes.  These must be in the same order
  611.             as they appear in the class declaration:
  612.  
  613.                  #define MEMBER_CLASSES C::desc(), D::desc()
  614.  
  615.             If a class has no class members,  define  MEMBER_CLASSES,  but
  616.             give it no value.
  617.  
  618.             Set the symbol VIRTUAL_BASE_CLASSES to a list of the addresses
  619.             of  the  class descriptors for the virtual base classes of the
  620.             class you are defining.  These must be in the  same  order  as
  621.             they appear in the class declaration:
  622.  
  623.                  #define VIRTUAL_BASE_CLASSES B::desc()
  624.  
  625.             If   a   class   has   no   virtual   base   classes,   define
  626.             VIRTUAL_BASE_CLASSES, but give it no value.
  627.  
  628.             Now you are ready to call the DEFINE_CLASS macro:
  629.  
  630.                  DEFINE_CLASS(classname,version,identification,initor1,initor2)
  631.  
  632.             Classname is the name of the class you are defining.
  633.  
  634.             Version is the version number of the class you  are  defining.
  635.             It  should  be  changed whenever the format of the information
  636.             written by the  storer()  function  changes  such  that  older
  637.             versions of readFrom() can no longer interpret it correctly.
  638.  
  639.             Identification is  a  character  string  that  identifies  the
  640.             revision  level  of  the  implementation  of the class.  It is
  641.             simply stored in the class descriptor where you  can  retrieve
  642.             it by calling the function Class::ident().  The identification
  643.             parameter is intended for use with a revision  control  system
  644.             such  as  RCS  or SCCS.  NIH Library classes specify it as the
  645.             string  "$Header$",  which  RCS  replaces  with  the  revision
  646.             identification.
  647.  
  648.             Initor1 and initor2 are pointers to functions you  may  supply
  649.  
  650.  
  651.  
  652.             Page 10                                         May 25, 1990
  653.  
  654.  
  655.  
  656.  
  657.  
  658.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  659.  
  660.  
  661.             to   perform   initialization  for  the  class,  for  example,
  662.             initializing static data that the class uses.
  663.  
  664.             DEFINE_ABSTRACT_CLASS
  665.  
  666.             Abstract    classes    should    use     the     new     macro
  667.             DEFINE_ABSTRACT_CLASS       instead      of      DEFINE_CLASS.
  668.             DEFINE_ABSTRACT_CLASS has the same arguments as  DEFINE_CLASS;
  669.             the   only  difference  is  that  the  reader()  functions  it
  670.             generates  do   not   reference   the   class's   object   I/O
  671.             constructors,    and    shallowCopy()    is   defined   as   a
  672.             derivedClassResponsibility().
  673.  
  674.             Change to Class::className()
  675.  
  676.             The function className() returns the name of the class of  the
  677.             object   to   which  it  is  applied.   In  previous  releases
  678.             Class::className() does not do this.  Instead, it returns  the
  679.             name of the class described by the class object to which it is
  680.             applied.   This   release   eliminates   this   inconsistency:
  681.             className()  returns  "Class"  when  applied to an instance of
  682.             class Class.  The new function Class::name() returns the  name
  683.             of the class described by an instance of class Class.
  684.  
  685.             New member functions of class Class
  686.  
  687.             Class**  baseClasses()  returns  a  zero-terminated  array  of
  688.             pointers  to the class descriptors of the base classes of this
  689.             class.
  690.  
  691.             Class** memberClasses() returns  a  zero-terminated  array  of
  692.             pointers  to  the  class  descriptors of the member classes of
  693.             this class.
  694.  
  695.             Class** virtualBaseClasses() returns a  zero-terminated  array
  696.             of  pointers  to  the  class  descriptors  of the virtual base
  697.             classes of this class.
  698.  
  699.             unsigned long signature() returns the signature of this class.
  700.             The signature of a class is computed by hashing the signatures
  701.             of this class's base and member classes and the version number
  702.             of  this  class.  It is currently used by storeOn()/readFrom()
  703.             to prevent obsolete versions of objects from being read.
  704.  
  705.             const Class* Class::lookup(const char* name) returns a pointer
  706.             to  the  class  descriptor  object  for  the  class  with  the
  707.             specified name.  Class::lookup() returns 0 if the name is  not
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.             May 25, 1990                                         Page 11
  719.  
  720.  
  721.  
  722.  
  723.  
  724.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  725.  
  726.  
  727.             found.
  728.  
  729.             Changes to copy(), shallowCopy(), and deepCopy()
  730.  
  731.             In previous releases, shallowCopy() made a bitwise copy of  an
  732.             object, and deepCopy() first made a shallow copy of an object,
  733.             and then called the virtual  function  deepenShallowCopy()  to
  734.             convert   the  shallow  copy  to  a  deep  copy.   Each  class
  735.             reimplemented deepenShallowCopy() to handle any pointer member
  736.             variables contained in instances of its class.
  737.  
  738.             The problems with this approach are that  (1)  it  is  usually
  739.             unsafe  to  make  a  shallow  copy  of an object that contains
  740.             pointers, and (2) with Release 2.0 of the AT&T C++ Translator,
  741.             objects   may   contain   compiler-generated   pointers  which
  742.             deepenShallowCopy() cannot handle easily and portably.
  743.  
  744.             The following changes have been made in an  attempt  to  solve
  745.             these problems:
  746.  
  747.             Each class now reimplements the virtual function shallowCopy()
  748.             to  call the initialization constructor X::X(const X&) to make
  749.             a  shallow  copy  of  an  object.    The   implementation   of
  750.             shallowCopy()  is  the  same  for all classes and is generated
  751.             automatically by the DEFINE_CLASS macro:
  752.  
  753.                  Object* classname::shallowCopy()
  754.                  {
  755.                      return new classname(*this);
  756.                  }
  757.  
  758.             Object::deepCopy()   still   calls   the   virtual    function
  759.             deepenShallowCopy() to convert a shallow copy, now made by the
  760.             initialization constructor, to a deep copy.  Since the shallow
  761.             copy  is  no  longer  a  simple  bitwise copy, you may need to
  762.             change deepenShallowCopy() for some classes.
  763.  
  764.             In previous releases, copy() defaulted to deepCopy() since  it
  765.             was  unsafe  for  general  use.   Beginning with this release,
  766.             copy() defaults to shallowCopy() as it does  in  Smalltalk-80.
  767.             Also, Object::deepCopy() is no longer a virtual function.
  768.  
  769.             New function dumpOn() and changes to printOn()
  770.  
  771.             To make the printOn()  function  more  useful  in  application
  772.             programs,  it  has  been  changed  to print minimal formatting
  773.             information, the idea being that this can frequently be  added
  774.             by  an  application  to  suit its specific needs.  The virtual
  775.             function dumpOn() has been added to  assist  in  debugging  by
  776.             printing    more    detailed   information   than   printOn().
  777.             Object::dumpOn() prints the name of an object's class, a  left
  778.             square  bracket ("["), calls printOn(), then prints a matching
  779.             right    square    bracket    and    a    newline     ("]\n").
  780.             Collection::dumpOn()  does  the  same,  except that it applies
  781.  
  782.  
  783.  
  784.             Page 12                                         May 25, 1990
  785.  
  786.  
  787.  
  788.  
  789.  
  790.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  791.  
  792.  
  793.             dumpOn() to all objects in the collection instead  of  calling
  794.             printOn().   Other  classes reimplement dumpOn() to print more
  795.             appropriate information.
  796.  
  797.             By default, dumpOn() sends its  output  to  cerr.   A  default
  798.             argument has also been added to printOn() so that it writes to
  799.             cout by default.
  800.  
  801.             Changes to class Link
  802.  
  803.             Constructor Link(const Link&) changed to Link(Link*)
  804.  
  805.             The constructor Link(const Link&),  which  constructs  a  Link
  806.             that  points  to  the  argument Link, has been replaced by the
  807.             constructor Link(Link*).  This change was  necessary  so  that
  808.             shallowCopy()  could call the constructor Link(const Link&) to
  809.             make a bitwise copy.  We suggest  temporarily  commenting  out
  810.             the  declaration  of  this  constructor in the file Link.h and
  811.             recompiling the programs that depend upon it so you can easily
  812.             detect  and change the code using Link(const Link&) to use the
  813.             new Link(Link*) constructor instead.
  814.  
  815.             As a result of this change, Link::shallowCopy() is now enabled
  816.             and will return a bitwise copy of a Link.
  817.  
  818.             New function isListEnd()
  819.  
  820.             Class Link has a new member function bool  isListEnd(),  which
  821.             you  must  use to check for the end of a LinkedList instead of
  822.             checking for a pointer to Nil.  Compile your program with -DMI
  823.             to find the places where you need to make this change.
  824.  
  825.             Changes to class Iterator
  826.  
  827.             Iterator::shallowCopy() now produces a  shallow  copy  with  a
  828.             pointer  to  the same collection bound to the original instead
  829.             of to a shallow copy of the collection bound to the  original,
  830.             as  in  prior releases.  Iterator::deepCopy() works as before:
  831.             it produces a deep copy with a pointer to a deep copy  of  the
  832.             collection bound to the original.
  833.  
  834.             The member  variable  Object*  state  has  been  added,  which
  835.             collection  classes  can  use  to  associate  additional state
  836.             information with an Iterator.  For example, a collection class
  837.             implemented  as  a  tree structure can use state to point to a
  838.             Stack used to maintain the state of a traversal of  the  tree.
  839.             The   destructor  for  class  Iterator  calls  a  new  virtual
  840.             function, doFinish(),  which  a  class  that  uses  state  can
  841.             reimplement  to  delete  the state object when the Iterator is
  842.             destroyed.
  843.  
  844.             The  storeOn()  format  has  changed  as  a  result  of  these
  845.             modifications.
  846.  
  847.  
  848.  
  849.  
  850.             May 25, 1990                                         Page 13
  851.  
  852.  
  853.  
  854.  
  855.  
  856.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  857.  
  858.  
  859.             The function Object* Iterator::operator()() has been added  to
  860.             return a pointer to the current object, or 0 if there is none.
  861.  
  862.             Changes to class Dictionary
  863.  
  864.             The return type of assocAt(), removeAssoc(),  and  removeKey()
  865.             has been changed from LookupKey& to LookupKey* for consistency
  866.             with    the    return    types    of    similar     functions.
  867.             Dictionary::assocAt()  returns  0 instead of nil if the key is
  868.             not found.
  869.  
  870.             const arguments to member functions
  871.  
  872.             In previous versions , it was possible to convert, or "widen",
  873.             a  pointer  to  a  const  object into a pointer to a non-const
  874.             object by adding the const object to a  collection  class  and
  875.             then removing it:
  876.  
  877.                  Object* f(const Object& co)
  878.                  {
  879.                      OrderedCltn c;
  880.                      c.add(co);
  881.                      return c.remove(co);
  882.                  }
  883.  
  884.             C++ R2.0 now issues error or warning  messages  when  a  const
  885.             pointer  is  converted into a non-const pointer.  To eliminate
  886.             these problems, the const arguments to some functions such  as
  887.             add() have been changed to non-const arguments.  These changes
  888.             affect classes Assoc, LinkOb, and the collection classes.
  889.  
  890.             If you need to add a const object to a collection  class,  you
  891.             must use an explicit cast:
  892.  
  893.                  c.add((Object&)co);
  894.  
  895.             Change to Bag::remove(const Object&)
  896.  
  897.             Bag::remove(const Object&) now returns 0 until last occurrence
  898.             removed  instead  of  the address of the argument to eliminate
  899.             "widening" of the const argument.
  900.  
  901.             shouldNotImplement() functions now private
  902.  
  903.             Virtual member functions that a  class  reimplements  to  call
  904.             shouldNotImplement()  have  been  made  private  so  that  the
  905.             compiler can  give  an  error  message  if  a  client  program
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.             Page 14                                         May 25, 1990
  917.  
  918.  
  919.  
  920.  
  921.  
  922.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  923.  
  924.  
  925.             attempts to apply the function to an instance of the class.
  926.  
  927.             Change to class Stack
  928.  
  929.             When a Stack is converted to another type of  collection,  the
  930.             objects  in the Stack are added to the collection from the top
  931.             of the stack down.  Previous releases added them bottom-up.
  932.  
  933.             Changes to class Heap
  934.  
  935.             The new member function Heap::removeId(const  Object&)  allows
  936.             you  to  remove the object that is the same (i.e. isSame()) as
  937.             the argument object from a Heap.
  938.  
  939.             Iterating over a Heap now visits the objects in  the  heap  in
  940.             sorted    order,   from   smallest   to   largest.    Previous
  941.             implementations visited  the  objects  in  heap  order.   This
  942.             affects  the  order  in which printOn() lists the objects in a
  943.             Heap, for example.
  944.  
  945.             Changes to class LinkedList
  946.  
  947.             The new member  function  LinkedList::removeId(const  Object&)
  948.             allows  you  to  remove  the  object  that  is  the same (i.e.
  949.             isSame()) as the argument object from a LinkedList.
  950.  
  951.             Changes to class LookupKey
  952.  
  953.             The virtual function Object* LookupKey::value() const has been
  954.             replaced by two virtual functions
  955.  
  956.                  virtual Object* value();
  957.                  virtual const Object* value() const;
  958.  
  959.             to  prevent  obtaining  a  non-const  pointer  from  a   const
  960.             LookupKey.
  961.  
  962.             Changes to class Arraychar
  963.  
  964.             The constructor  for  class  Arraychar  now  initializes  each
  965.             element of the the array to 0.
  966.  
  967.             The virtual function removeAll() has been  implemented,  which
  968.             resets each element of the array to 0.
  969.  
  970.             Changes to class Assoc
  971.  
  972.             The virtual function Object*  Assoc::value()  const  has  been
  973.             replaced by two virtual functions
  974.  
  975.                  virtual Object* value();
  976.                  virtual const Object* value() const;
  977.  
  978.  
  979.  
  980.  
  981.  
  982.             May 25, 1990                                         Page 15
  983.  
  984.  
  985.  
  986.  
  987.  
  988.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  989.  
  990.  
  991.             to prevent obtaining a non-const pointer from a const Assoc.
  992.  
  993.             Changes to class AssocInt
  994.  
  995.             The virtual function Object* AssocInt::value() const has  been
  996.             replaced by two virtual functions
  997.  
  998.                  virtual Object* value();
  999.                  virtual const Object* value() const;
  1000.  
  1001.             to  prevent  obtaining  a  non-const  pointer  from  a   const
  1002.             AssocInt.
  1003.  
  1004.  
  1005.  
  1006.             CHANGES BETWEEN OOPS V2R1 AND OOPS V2R2
  1007.  
  1008.             Class name changes
  1009.  
  1010.             The name of class Arrayobid is now ArrayOb, the name of  class
  1011.             Linkobid is now LinkOb, and the typedef obid has been removed.
  1012.             Just change all occurrences of Arrayobid to ArrayOb,  Linkobid
  1013.             to LinkOb, and obid to Object*.
  1014.  
  1015.             Type bool now int
  1016.  
  1017.             Type bool has been changed from char to int for  compatibility
  1018.             with X V11.
  1019.  
  1020.             New String class
  1021.  
  1022.             There is a new, more efficient implementation of class String.
  1023.             The  new  String class is compatible with the old String class
  1024.             except for the following:
  1025.  
  1026.                  String(char c, unsigned l =1);
  1027.  
  1028.             is now:
  1029.  
  1030.                  String(char& c, unsigned l=1,
  1031.                      unsigned extra=DEFAULT_STRING_EXTRA);
  1032.  
  1033.             The argument unsigned extra has been  added  to  most  of  the
  1034.             String::String()  constructors to allow the programmer to give
  1035.             a hint as to how much space to  allocate  in  the  string  for
  1036.             additional  characters.   When  properly used, this can reduce
  1037.             the number of calls made to the memory allocator.
  1038.  
  1039.             Assignment to substrings has changed slightly.  The old String
  1040.             class handled an assignment to a substring such as:
  1041.  
  1042.                  String s = "abcdef";
  1043.                  s(0,2) = "123";         // result is 12cdef
  1044.  
  1045.  
  1046.  
  1047.  
  1048.             Page 16                                         May 25, 1990
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  1055.  
  1056.  
  1057.             by  truncating  the  source  string  to  the  length  of   the
  1058.             destination substring.  An assignment such as:
  1059.  
  1060.                  s(0,2) = "1";           // result is 1\0cdef
  1061.  
  1062.             would cause a null byte to  be  inserted  in  the  destination
  1063.             substring.
  1064.  
  1065.             The new String class replaces the target  substring  with  the
  1066.             source  string,  adjusting  the length of the target string if
  1067.             necessary.  Thus
  1068.  
  1069.                  String s = "abcdef";
  1070.                  s(0,2) = "123";         // result is 123cdef
  1071.  
  1072.             and:
  1073.  
  1074.                  s(0,2) = "1";           // result is 1cdef
  1075.  
  1076.             Changes to Class Process
  1077.  
  1078.             An interface to select(2) has been added:
  1079.  
  1080.                  void Process::select(FDSet& rdmask, FDSet& wrmask, FDSet&
  1081.                  exmask);
  1082.  
  1083.  
  1084.  
  1085.             PORTING THE PROCESS CLASSES
  1086.  
  1087.             This section describes the steps to follow if you want to be a
  1088.             pioneer    and   port   the   Process   classes   to   a   new
  1089.             machine/operating system.
  1090.  
  1091.             If  your  target  system  provides  the  C  library   routines
  1092.             setjmp(),  longjmp(),  and alloca(), and if the implementation
  1093.             of setjmp()/longjmp() operates by saving/restoring all of  the
  1094.             machine's  volatile registers (as they do on the Sun-3, Sun-4,
  1095.             and IBM RT/AOS), then the port should be very easy; otherwise,
  1096.             you'll  need  to  write versions of these routines in assembly
  1097.             language that behave as expected.
  1098.  
  1099.             To find out how your setjmp()/longjmp() works, either look  at
  1100.             the source code for these routines (if you're fortunate enough
  1101.             to have it) or use the debugger to disassemble them.   A  data
  1102.             structure  of  type jmp_buf, defined in setjmp.h, is passed as
  1103.             an argument to these routines.  If your  setjmp()  just  saves
  1104.             all  the  volatile  registers  in  it  to be restored later by
  1105.             longjmp(), then you're probably  in  luck---all  you  need  to
  1106.             figure  out are the offsets in the jmp_buf structure where the
  1107.             PC (Program  Counter),  SP  (Stack  Pointer),  and  FP  (Frame
  1108.             Pointer) registers are saved.
  1109.  
  1110.             Next, look at nihclconfig.h and  locate  the  place  where  it
  1111.  
  1112.  
  1113.  
  1114.             May 25, 1990                                         Page 17
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  1121.  
  1122.  
  1123.             defines   the   machine-specific  inline  functions  SETJMP(),
  1124.             LONGJMP(),  _SETJMP(),  _LONGJMP(),  ENV_PC(),  ENV_SP(),  and
  1125.             ENV_FP().   These define the interface to the Process classes.
  1126.             For example, here are the definitions for  SunOS  4.0  on  the
  1127.             Sun-3:
  1128.  
  1129.                  #ifdef SUNOS4
  1130.  
  1131.                  #ifdef mc68000
  1132.                  typedef jmp_buf JMP_BUF;
  1133.                  inline int SETJMP(JMP_BUF env)              { return
  1134.                  setjmp(env); }
  1135.                  inline void LONGJMP(JMP_BUF env, int val)   {
  1136.                  longjmp(env,val); }
  1137.                  inline int _SETJMP(JMP_BUF env)             { return
  1138.                  _setjmp(env); }
  1139.                  inline void _LONGJMP(JMP_BUF env, int val)  {
  1140.                  _longjmp(env,val); }
  1141.                  inline unsigned& ENV_PC(JMP_BUF env)
  1142.                                      { return (unsigned&)env[3]; }
  1143.                  inline unsigned& ENV_SP(JMP_BUF env)
  1144.                                      { return (unsigned&)env[2]; }
  1145.                  inline unsigned& ENV_FP(JMP_BUF env)
  1146.                                      { return (unsigned&)env[15]; }
  1147.                  #endif
  1148.  
  1149.                  // ...
  1150.                  #endif
  1151.  
  1152.             Add an #if ... #endif section for your machine and define  the
  1153.             ENV_PC(),   ENV_SP(),  and  ENV_FP()  functions  to  return  a
  1154.             reference to the appropriate word in the JMP_BUF array.
  1155.  
  1156.             If your machine doesn't use both an SP  and  FP,  then  you'll
  1157.             also need to add some machine dependent C++ code to HeapProc.c
  1158.             to relocate only the one actually used.  See the code for  the
  1159.             ibm032 in HeapProc.c as an example.
  1160.  
  1161.             If   your   system    has    both    setjmp()/longjmp()    and
  1162.             _setjmp()/_longjmp(),  define  SETJMP(), LONGJMP(), _SETJMP(),
  1163.             and _LONGJMP() to call the  corresponding  routine.   If  your
  1164.             system doesn't have the "_" versions, check your documentation
  1165.             to see if  your  setjmp()/longjmp()  saves  and  restores  the
  1166.             signal  mask;  if  so, define _SETJMP() and _LONGJMP() to call
  1167.             setjmp() and longjmp(), respectively.  See the code for SUNOS3
  1168.             as an example.
  1169.  
  1170.             If your setjmp() and longjmp() do not  save  and  restore  the
  1171.             signal  mask, you'll need to provide versions that do.  Define
  1172.             JMP_BUF to be  a  struct  that  consists  of  a  jmp_buf  plus
  1173.             whatever other members you need to save the signal mask.  Then
  1174.             define _SETJMP() and _LONGJMP() to call setjmp() and longjmp()
  1175.             using  the  jmp_buf part of a JMP_BUF, and define SETJMP() and
  1176.             LONGJMP() to do the same, but in addition to save/restore  the
  1177.  
  1178.  
  1179.  
  1180.             Page 18                                         May 25, 1990
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  1187.  
  1188.  
  1189.             signal  mask  using  the  other members of a JMP_BUF.  See the
  1190.             code for the mc300 as an example.
  1191.  
  1192.             If your setjmp()/longjmp() do not work by saving/restoring all
  1193.             volatile  registers  (as  on  the  VAX),  you'll need to write
  1194.             versions with different names that do, and call these  instead
  1195.             from the interface functions.
  1196.  
  1197.             If you succeed  in  porting  the  Process  classes  to  a  new
  1198.             machine/operating  system,  we'd appreciate a copy of the code
  1199.             for inclusion in future releases.
  1200.  
  1201.  
  1202.  
  1203.             AT&T C++ TRANSLATOR RELEASE 2.00/2.1 BUGS
  1204.  
  1205.             Releases 2.00 and R2.1 of the AT&T C++ Translator have  a  few
  1206.             bugs  that  we had to insert work-arounds for in the NIH Class
  1207.             Library.   These  are  conditionally  compiled  based  on  the
  1208.             definition  of  preprocessor  symbols beginning with BUG_.  If
  1209.             you are using the NIH Class Library to test a Release 2.00  or
  1210.             2.1  -compatible  C++  compiler,  we suggest that you edit the
  1211.             master Makefile to define these symbols:
  1212.  
  1213.                  # Disable AT&T R2.0/R2.1 bug work-around code
  1214.                  #BUGDEFS =
  1215.                  BUGDEFS = -DBUG_bC2728 -DBUG_38 -DBUG_39
  1216.                  -DBUG_OPTYPECONST
  1217.  
  1218.  
  1219.  
  1220.             YACC STACK OVERFLOWS
  1221.  
  1222.             The preprocessor symbol  BUG_TOOBIG  controls  compilation  of
  1223.             code we had to insert to avoid "yacc stack overflow" errors in
  1224.             the  SunOS  3.5  C  compiler.   Release  2.0   produces   very
  1225.             complicated  expressions  for  the inline copy constructors it
  1226.             generates for  deeply-derived  classes.   Explicitly  defining
  1227.             non-inline copy constructors solves the problem.  If you are a
  1228.             C compiler vendor, please  make  your  tables  big  enough  to
  1229.             handle the C code generated by the AT&T C++ Translator!
  1230.  
  1231.  
  1232.  
  1233.             COMPILING UNDER AT&T C++ TRANSLATOR RELEASE 2.1
  1234.  
  1235.             R3.0 of the NIH Class Library has been tested with Release 2.1
  1236.             of  the  AT&T  C++  Translator under SunOS 4.0.  The following
  1237.             subsections summarize the changes required when compiling with
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.             May 25, 1990                                         Page 19
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  1253.  
  1254.  
  1255.             R2.1.
  1256.  
  1257.             Inconsistent declarations of alloca() in header files
  1258.  
  1259.             The header files supplied with R2.1 declare  alloca()  with  a
  1260.             return type of void* in alloca.h and char* in malloc.h, so you
  1261.             get an error message from the  compiler  when  both  of  these
  1262.             files  are  included  in the same compilation unit.  We solved
  1263.             this problem by changing the return type of the declaration of
  1264.             alloca() in malloc.h to void*.
  1265.  
  1266.             Warning and error messages due to #pragmas in SunOS 4.0 header
  1267.             files
  1268.  
  1269.             The C compiler occasionally issues warning  messages  such  as
  1270.             the  following  when  compiling  the  output  of  the AT&T C++
  1271.             Translator (both R2.0 and R2.1) under SunOS 4.0:
  1272.  
  1273.                  "/usr/include/CC/sys/signal.h",  line  38:  warning:
  1274.                  function name expected
  1275.  
  1276.             This is because C++ doesn't understand the #pragma  directives
  1277.             it  encounters in some system header files,  so it just passes
  1278.             them through to the C compiler.  The warning  message  results
  1279.             because  C++  eliminates  or moves the C function declarations
  1280.             that the pragma references.  Another problem is that  the  C++
  1281.             header   files   use  #define  to  temporarily  rename  system
  1282.             functions when they include the vendor's C header files  as  a
  1283.             way  to  hide  the  effects of the vendor's C declarations for
  1284.             these functions.  Unfortunately,  this  garbles  the  function
  1285.             names in the #pragma directives also.
  1286.  
  1287.             Under R2.0,  the  #pragma  problem  just  results  in  warning
  1288.             messages, but under R2.1, the C compilation occasionally fails
  1289.             with an error message.  We manually made a new, self-contained
  1290.             version  of /usr/include/CC/setjmp.h with the following pragma
  1291.             at the end:
  1292.  
  1293.                  /*
  1294.                   * Routines that call setjmp have strange control flow
  1295.                  graphs,
  1296.                   * since a call to a routine that calls resume/longjmp
  1297.                  will eventually
  1298.                   * return at the setjmp site, not the original call site.
  1299.                  This
  1300.                   * utterly wrecks control flow analysis.
  1301.                   */
  1302.                  #pragma unknown_control_flow(sigsetjmp, setjmp, _setjmp)
  1303.  
  1304.             This eliminates  the  error  messages,  but  not  the  warning
  1305.             messages.   It would probably be no worse to simply remove the
  1306.             #pragmas altogether, since they don't seem to  be  having  the
  1307.             intended effect, and that would eliminate the warning messages
  1308.  
  1309.  
  1310.  
  1311.  
  1312.             Page 20                                         May 25, 1990
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  1319.  
  1320.  
  1321.             also.
  1322.  
  1323.             C++ Translator +p option broken
  1324.  
  1325.             The +p option produces spurious errors under R2.1.   Edit  the
  1326.             master  Makefile  to not use the +p option when compiling with
  1327.             R2.1:
  1328.  
  1329.                  # C++ flags
  1330.                  # NOTE: Disable +p option when compiling with AT&T R2.1
  1331.                  #CCFLAGS = +p
  1332.                  CCFLAGS =
  1333.  
  1334.             Optional support for nested types
  1335.  
  1336.             You can optionally define the preprocessor symbol NESTED_TYPES
  1337.             to cause the NIH Class Library to use nested types under R2.1.
  1338.             Edit the master Makefile as follows:
  1339.  
  1340.                  # Compile with nested types (works with AT&T R2.1 and GNU
  1341.                  C++)
  1342.                  #NESTED_TYPES =
  1343.                  NESTED_TYPES = -DNESTED_TYPES
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.             May 25, 1990                                         Page 21
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.             Release Notes  NIH Class Library Revision 3.0  Release Notes
  1385.  
  1386.  
  1387.                  DN
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.             Page 22                                         May 25, 1990
  1445.  
  1446.  
  1447.